<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Uri - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.uri.chapter.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.uri.chapter.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.uri.html">Zend_Uri</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.uri.html">Zend_Uri</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.validate.html">Zend_Validate</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.uri.chapter" class="section"><div class="info"><h1 class="title">Zend_Uri</h1></div>
    

    <div class="section" id="zend.uri.overview"><div class="info"><h1 class="title">Overview</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Uri</span> is a component that aids in manipulating and validating
            <a href="http://www.w3.org/Addressing/" class="link external">&raquo; Uniform Resource Identifiers</a> (URIs).
            <span class="classname">Zend_Uri</span> exists primarily to service other components, such as
            <span class="classname">Zend_Http_Client</span>, but is also useful as a standalone utility.
        </p>

        <p class="para">
            <acronym class="acronym">URI</acronym>s always begin with a scheme, followed by a colon. The
            construction of the many different schemes varies significantly. The
            <span class="classname">Zend_Uri</span> class provides a factory that returns a subclass
            of itself which specializes in each scheme. The subclass will be named
            <span class="classname">Zend_Uri_&lt;scheme&gt;</span>, where
            <em class="emphasis">&lt;scheme&gt;</em> is the scheme, lowercased with the first letter
            capitalized. An exception to this rule is <acronym class="acronym">HTTPS</acronym>, which is also
            handled by <span class="classname">Zend_Uri_Http</span>.
        </p>
    </div>

    <div class="section" id="zend.uri.creation"><div class="info"><h1 class="title">Creating a New URI</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Uri</span> will build a new <acronym class="acronym">URI</acronym> from scratch
            if only a scheme is passed to  <span class="methodname">Zend_Uri::factory()</span>.
        </p>

        <div class="example" id="zend.uri.creation.example-1"><div class="info"><p><b>Example #1 Creating a New URI with Zend_Uri::factory()</b></p></div>
            

            <pre class="programlisting brush: php">
// To create a new URI from scratch, pass only the scheme.
$uri = Zend_Uri::factory(&#039;http&#039;);

// $uri instanceof Zend_Uri_Http
</pre>

        </div>

        <p class="para">
            To create a new <acronym class="acronym">URI</acronym> from scratch, pass only the scheme to
             <span class="methodname">Zend_Uri::factory()</span><a href="#fnid1" name="fn1"><sup>[1]</sup></a><span class="classname">Zend_Uri</span><acronym class="acronym">HTTP</acronym><acronym class="acronym">HTTPS</acronym>. If an unsupported scheme is
            passed and no scheme-specific class is specified, a <span class="classname">Zend_Uri_Exception</span>
            will be thrown.
        </p>

        <p class="para">
            If the scheme or <acronym class="acronym">URI</acronym> passed is supported,
             <span class="methodname">Zend_Uri::factory()</span> will return a subclass of itself that
            specializes in the scheme to be created.
        </p>

        <div class="section"><div class="info"><h1 class="title">Creating a New Custom-Class URI</h1></div>
            

            <p class="para">
                Starting from Zend Framework 1.10.5, you can specify a custom class to be
                used when creating the Zend_Uri instance, as a second parameter to the
                 <span class="methodname">Zend_Uri::factory()</span> method.
                This enables you to subclass Zend_Uri and create your own custom URI classes,
                and instantiate new URI objects based on your own custom classes.
            </p>

            <p class="para">
                The 2nd parameter passed to  <span class="methodname">Zend_Uri::factory()</span> must
                be a string with the name of a class extending <span class="classname">Zend_Uri</span>.
                The class must either be alredy-loaded, or loadable using  <span class="methodname">Zend_Loader::loadClass()</span> -
                that is, it must follow the Zend Framework class and file naming conventions, and
                must be in your include_path.
            </p>

            <div class="example" id="zend.uri.creation.custom.example-1"><div class="info"><p><b>Example #2 Creating a URI using a custom class</b></p></div>
                

                <pre class="programlisting brush: php">
// Create a new &#039;ftp&#039; URI based on a custom class
$ftpUri = Zend_Uri::factory(
    &#039;ftp://user@ftp.example.com/path/file&#039;,
    &#039;MyLibrary_Uri_Ftp&#039;
);

// $ftpUri is an instance of MyLibrary_Uri_Ftp, which is a subclass of Zend_Uri
</pre>

            </div>
        </div>

    </div>

    <div class="section" id="zend.uri.manipulation"><div class="info"><h1 class="title">Manipulating an Existing URI</h1></div>
        

        <p class="para">
            To manipulate an existing <acronym class="acronym">URI</acronym>, pass the entire <acronym class="acronym">URI</acronym>
            to  <span class="methodname">Zend_Uri::factory()</span>.
        </p>

        <div class="example" id="zend.uri.manipulation.example-1"><div class="info"><p><b>Example #3 Manipulating an Existing URI with Zend_Uri::factory()</b></p></div>
            

            <pre class="programlisting brush: php">
// To manipulate an existing URI, pass it in.
$uri = Zend_Uri::factory(&#039;http://www.zend.com&#039;);

// $uri instanceof Zend_Uri_Http
</pre>

        </div>

        <p class="para">
            The <acronym class="acronym">URI</acronym> will be parsed and validated. If it is found to be invalid,
            a <span class="classname">Zend_Uri_Exception</span> will be thrown immediately. Otherwise,
             <span class="methodname">Zend_Uri::factory()</span> will return a subclass of itself that
            specializes in the scheme to be manipulated.
        </p>
    </div>

    <div class="section" id="zend.uri.validation"><div class="info"><h1 class="title">URI Validation</h1></div>
        

        <p class="para">
            The  <span class="methodname">Zend_Uri::check()</span> method can only be used if validation
            of an existing <acronym class="acronym">URI</acronym> is needed.
        </p>

        <div class="example" id="zend.uri.validation.example-1"><div class="info"><p><b>Example #4 URI Validation with Zend_Uri::check()</b></p></div>
            

            <pre class="programlisting brush: php">
// Validate whether a given URI is well formed
$valid = Zend_Uri::check(&#039;http://uri.in.question&#039;);

// $valid is TRUE for a valid URI, or FALSE otherwise.
</pre>

        </div>

        <p class="para">
             <span class="methodname">Zend_Uri::check()</span> returns a boolean, which is more convenient
            than using  <span class="methodname">Zend_Uri::factory()</span> and catching the exception.
        </p>

        <div class="section" id="zend.uri.validation.allowunwise"><div class="info"><h1 class="title">Allowing &quot;Unwise&quot; characters in URIs</h1></div>
            

            <p class="para">
                By default, <span class="classname">Zend_Uri</span> will not accept the following
                characters: <em class="emphasis">&quot;{&quot;, &quot;}&quot;, &quot;|&quot;, &quot;\&quot;, &quot;^&quot;, &quot;`&quot;</em>. These characters are
                defined by the <acronym class="acronym">RFC</acronym> as &quot;unwise&quot; and invalid; however, many
                implementations do accept these characters as valid.
            </p>

            <p class="para">
                <span class="classname">Zend_Uri</span> can be set to accept these &quot;unwise&quot; characters by
                setting the &#039;allow_unwise&#039; option to boolean <b><tt>TRUE</tt></b> using
                 <span class="methodname">Zend_Uri::setConfig()</span>:
            </p>

            <div class="example" id="zend.uri.validation.allowunwise.example-1"><div class="info"><p><b>Example #5 Allowing special characters in URIs</b></p></div>
                

                <pre class="programlisting brush: php">
// Contains &#039;|&#039; symbol
// Normally, this would return false:
$valid = Zend_Uri::check(&#039;http://example.com/?q=this|that&#039;);

// However, you can allow &quot;unwise&quot; characters
Zend_Uri::setConfig(array(&#039;allow_unwise&#039; =&gt; true));

// will return &#039;true&#039;
$valid = Zend_Uri::check(&#039;http://example.com/?q=this|that&#039;);

// Reset the &#039;allow_unwise&#039; value to the default FALSE
Zend_Uri::setConfig(array(&#039;allow_unwise&#039; =&gt; false));
</pre>

            </div>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                     <span class="methodname">Zend_Uri::setConfig()</span> sets configuration options
                    globally. It is recommended to reset the &#039;allow_unwise&#039; option to
                    &#039;<b><tt>FALSE</tt></b>&#039;, like in the example above, unless you are certain
                    you want to always allow unwise characters globally.
                </p>
            </p></blockquote>
        </div>
    </div>

    <div class="section" id="zend.uri.instance-methods"><div class="info"><h1 class="title">Common Instance Methods</h1></div>
        

        <p class="para">
            Every instance of a <span class="classname">Zend_Uri</span> subclass (e.g.
            <span class="classname">Zend_Uri_Http</span>) has several instance methods that are useful for
            working with any kind of <acronym class="acronym">URI</acronym>.
        </p>

        <div class="section" id="zend.uri.instance-methods.getscheme"><div class="info"><h1 class="title">Getting the Scheme of the URI</h1></div>
            

            <p class="para">
                The scheme of the <acronym class="acronym">URI</acronym> is the part of the <acronym class="acronym">URI</acronym>
                that precedes the colon. For example, the scheme of
                <var class="filename">http://www.zend.com</var> is &#039;http&#039;.
            </p>

            <div class="example" id="zend.uri.instance-methods.getscheme.example-1"><div class="info"><p><b>Example #6 Getting the Scheme from a Zend_Uri_* Object</b></p></div>
                

                <pre class="programlisting brush: php">
$uri = Zend_Uri::factory(&#039;http://www.zend.com&#039;);

$scheme = $uri-&gt;getScheme();  // &quot;http&quot;
</pre>

            </div>

            <p class="para">
                The  <span class="methodname">getScheme()</span> instance method returns only the scheme
                part of the <acronym class="acronym">URI</acronym> object.
            </p>
        </div>

        <div class="section" id="zend.uri.instance-methods.geturi"><div class="info"><h1 class="title">Getting the Entire URI</h1></div>
            

            <div class="example" id="zend.uri.instance-methods.geturi.example-1"><div class="info"><p><b>Example #7 Getting the Entire URI from a Zend_Uri_* Object</b></p></div>
                

                <pre class="programlisting brush: php">
$uri = Zend_Uri::factory(&#039;http://www.zend.com&#039;);

echo $uri-&gt;getUri();  // &quot;http://www.zend.com&quot;
</pre>

            </div>

            <p class="para">
                The  <span class="methodname">getUri()</span> method returns the string representation
                of the entire <acronym class="acronym">URI</acronym>.
            </p>
        </div>

        <div class="section" id="zend.uri.instance-methods.valid"><div class="info"><h1 class="title">Validating the URI</h1></div>
            

            <p class="para">
                 <span class="methodname">Zend_Uri::factory()</span> will always validate any
                <acronym class="acronym">URI</acronym> passed to it and will not instantiate a new
                <span class="classname">Zend_Uri</span> subclass if the given <acronym class="acronym">URI</acronym> is
                found to be invalid. However, after the <span class="classname">Zend_Uri</span> subclass is
                instantiated for a new <acronym class="acronym">URI</acronym> or an existing valid one, it is
                possible that the <acronym class="acronym">URI</acronym> can later become invalid after it
                is manipulated.
            </p>

            <div class="example" id="zend.uri.instance-methods.valid.example-1"><div class="info"><p><b>Example #8 Validating a Zend_Uri_* Object</b></p></div>
                

                <pre class="programlisting brush: php">
$uri = Zend_Uri::factory(&#039;http://www.zend.com&#039;);

$isValid = $uri-&gt;valid();  // TRUE
</pre>

            </div>

            <p class="para">
                The  <span class="methodname">valid()</span> instance method provides a means to check that
                the <acronym class="acronym">URI</acronym> object is still valid.
            </p>
        </div>
    </div>
<div class="footnote"><a name="fnid1" href="#fn1"><sup>[1]</sup></a><span class="para footnote">At the time of writing,
             only provides built-in support for the 
            and  schemes.</span></div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.uri.html">Zend_Uri</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.uri.html">Zend_Uri</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.validate.html">Zend_Validate</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.uri.html">Zend_Uri</a></li>
  <li class="active"><a href="zend.uri.chapter.html">Zend_Uri</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>